.H Groff 1
.LP
Groff is the most widespread implementation of the troff program,
itself a spin of roff
(of which there is also nroff
and neatroff).
Is commonly viwed as the language you write Unix man pages in,
but it can be used for general document typesetting akin to Tex
and Latex.
.PP
Groff works creating by building on primitives
and creating macros.
There is already some default macros packages that ship with the program.
They are:
.BL
.I an :
Used for man pages.
.BL
.I doc:
Newer version of man pages.
.BL
.I s:
The original AT&T document format (remember this software is old).
.BL
.I e:
A Berkeley alternative to the AT&T macro suite.
.BL
.I m:
Second generation AT&T macro suite, sucessor to
.I s.
.BL
.I om:
Modern macro packages specifically made for Groff.
.PP
The short names are historical products of the limations of the UNIX system.
Also,
due to how the packages where specified in the command line
(through the flag
.I -m ).
They are commonly refered with the letter 'm' prepended to them.
For example,
.I om
becomes
.I mom
and
.I s
becomes
.I ms
and so on
and so forth.
Currently, I'm only using
.I ms ,
so that's what I will cover.
To get you started,
here is a sample
.I ms
document:
.
.
.CBS Sample Groff source code.
.NH
This is a section.
.LP
This is a left aligned paragraph detailing some information.
.NH
This is a section with a depth of 2.
.SH
This is a unumbered header.
.PP
This paragraph will have some indentation.
.B "Make this text bold" .
.
.PP
Here is another indented paragraph.
.CBE
.
.
.PP
In Groff 
(and it's variants)
the typesetting is done via calling macros,
which are called by putting the dot (".") character in the beginning of the line,
followed by the macro name.
The general workflow goes like this:
call a macro for typesetting
(say 
.I .NH
or 
.I .LP ),
then write the appropriate text in the next line.
Ocasionally,
the text meant for formatting is passed, 
as arguments,
to the macro being called.
In this case,
the arguments go in the same line as the macro call.
Here is an example:
.CBS A macro call with arguments.
.MACRO "first argument" second
.CBE
.
.H "Headers and the table of contents"
.PP
Headers are usually done using either
.CW NH
or
.CW SH
for numbered
and unnumbered headers respectively.
Calls to
.CW .NH
automatically increment the header counter
and Groff throws an error when the depth is improperly defined.
.PP
Now,
to make a table of contents,
you need to mix these macros with either the
.CW .XH
or the
.CW .XS
macros,
if you want a more automatic approach,
or you can use the
.CW .XS
or
.CW .XE
macros for more control.
.CBS Table of contents example.
.NH 
.XN Simple table of contents with header.
.
.NH
More involved approach for TOC construction.
.XS
More involved approach for TOC construction.
.XE
.
.TC
.CBE
.PP
Notice that,
when using the
.CW .XN
macro,
we only have to type the header text once.
The
.CW .XS
and
.CW .XE
macros require repeating the header text,
but also allows the formatting of the header text
and the TOC entry to differ.
Lastly,
to generate the table of contents proper,
we call the
.CW .TC
macro.
It usually goes in the end of the document,
so that groff can automatically collect the entries
and their pages to generate the TOC.
.PP
This has the side effect of placing the TOC in the end of the document.
Historically,
the TOC was moved after being printed,
so it wasn't much of an issue,
but now is common to read PDF documents digitally,
thus we need a way to move it.
.PP
One common way is to after the documente generation using tools like
.CW pdfjam .
Groff also has wrappers that can do this for you either by using
.CW pdfroff
directly in your document generation pipeline
or by calling Groff with the
.CW -mspdf
flag.
Alternatively,
my preffered solution is to use a couple of macros offered by the
.CW gropdf
tool:
.CW .pdfpagename
and
.CW switchtopage .
.CBS Moving TOC with \f[CW].pdfpagename\f[] and \f[CW]swtichtopage\f[] macros.
.pdfpagename first
.NH
.XN A header
.NH 2
.XN A header with depth 2
.switchtopage first
.TC
.CBE
.PP
Notice how we specify the page name in the
.CW .pdfpagename
call
(while also putting in the top of the document,
making sure it refers to the first page of the document)
and refer back to it later in
.CW .switchtopage .
.
.H "Bold and italics"
.PP
Some formatting,
like bold or italics,
are done for just a particular part of a sentence,
before returning to the default formatting.
In these cases,
we usually put the whole word together with the macro call,
in a single line
(e.g
.CW ".B bold" ).
Though, we can also use the 
.CW \\\f
escape sequence
to select the italic or bold font.
For example:
.CBS Groff bold and italics example.
.PP
A normal paragraph with a
.B bold
word and a
.I italic
word.
We can also
.B "Have multiple bold"
.I "or various italic lines"
.
\# The second argument goes immediately after.
\# And the third goes immediately before.
.B "bold words in parentheses" ) (
.I "italic words in parentheses" ) (
.
In a single macro call.
We can also make \f[B]bold\f[] like this;
\f[I]italics\f[] like this;
and \f[BI]bold italic\f[] like this.
.CBE
.PP
Notice that we specify the font type
(bold, italic or both)
inside the square brackets,
and that,
to restore to the previous font
we make an
.CW \\\f[] call.
Lastly,
keep in mind that the second and third arguments to either a
.CW .B
or a
.CW I
macro calls are the text placed immediately after and before the typeset word.
